• Implement engine.io WebSocket transport-level packet packing to reduce frame overhead
• Monkey-patch WebSocket transport to coalesce multi-packet sends into single frames
• Add enginePacking setting (default false) with forward-compatibility warnings
• Maintain single-packet fast path for steady-state quiet-pad behavior

New engine.io WebSocket packing patch module

• New module implementing WebSocket transport monkey-patch for packet coalescing
• Resolves engine.io's encodePayload and patches WebSocketTransport.prototype.send
• Multi-packet sends (N > 1) go through encodePayload and emit single WS frame
• Single-packet sends preserve legacy fast path with pre-encoded-frame optimization
• Includes idempotent installation guard and error handling with logging

src/node/utils/EnginePacking.ts

Conditionally install engine packing at server boot

• Add conditional lazy-loading of EnginePacking module before socket.io Server construction
• Call installEngineWsPacking() only when settings.enginePacking === true
• Ensures patched transport prototype is active when engine.io instantiates transports
• Lazy require prevents module load for deployments not using the feature

src/node/hooks/express/socketio.ts

Add enginePacking setting with forward-compatibility warnings

• Add enginePacking: boolean field to SettingsType type definition
• Add enginePacking: false default setting with comprehensive documentation
• Document warning about client forward-compatibility requirements
• Explain that multi-packet frames require clients to detect \x1e separator and use
 decodePayload
• Note that production deployments must coordinate rollouts with compatible browser bundles

src/node/utils/Settings.ts

Description

A new public config setting enginePacking is added and wired into server boot, but the user-facing
configuration documentation/template is not updated to include it. This risks operators being
unaware of the flag and its compatibility warning.

Code

src/node/utils/Settings.ts[R662-678]

+  /**
+   * Pack multiple engine.io packets into a single WebSocket frame
+   * (ether/etherpad#7756 lever 8). engine.io's WS transport otherwise
+   * sends one frame per packet, while the polling transport already
+   * batches via encodePayload. Enabling this matches the polling
+   * coalescing behaviour on the WS path; at high fan-out rates it cuts
+   * the WS frame count proportionally to packets-per-flush.
+   *
+   * WARNING: enabling this requires connected clients to recognise
+   * payload-encoded WS frames (split on the `\x1e` record separator
+   * and decodePayload). Clients that pass each frame straight to
+   * decodePacket will fail to parse a multi-packet frame and silently
+   * miss those messages. The etherpad browser bundle and
+   * etherpad-cli-client are forward-compatible (they detect the
+   * separator); third-party clients may not be. Coordinate rollouts.
+   */
+  enginePacking: false,

Evidence

The checklist requires documentation updates when adding/changing configuration. The PR adds the new
enginePacking setting (with warnings) in code, but the configuration template that documents
settings.json options does not include any enginePacking entry in the relevant socket.io/socket
transport section.

src/node/utils/Settings.ts[662-678]
settings.json.template[709-740]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new configuration option (`enginePacking`) was introduced and is used at runtime, but it is not documented in the repository’s configuration documentation, so users will not discover it or its rollout warnings.

## Issue Context
`enginePacking` is added to `SettingsType` and defaulted to `false` with detailed inline comments, and it gates a runtime behavior change in socket.io/engine.io startup.

## Fix Focus Areas
- settings.json.template[709-740]
- src/node/utils/Settings.ts[662-678]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

installEngineWsPacking() sets installed = true before verifying engine.io modules/shapes, so any
early return (missing modules or unexpected shape) prevents future install attempts in the same
process even though the patch was never applied.

Code

src/node/utils/EnginePacking.ts[R38-58]

+  if (installed) return;
+  installed = true;
+
+  let WebSocketTransport: any;
+  let encodePayload: any;
+  try {
+    // Resolve from inside engine.io's own dependency closure so we pick up
+    // exactly the engine.io-parser the transport uses, not a duplicate copy.
+    WebSocketTransport = require('engine.io/build/transports/websocket').WebSocket;
+    encodePayload = require('engine.io-parser').encodePayload;
+  } catch (err: any) {
+    logger.warn(`Unable to install engine.io WS packing (modules not found): ${err && err.message || err}`);
+    return;
+  }
+  if (typeof WebSocketTransport !== 'function' ||
+      typeof WebSocketTransport.prototype !== 'object' ||
+      typeof encodePayload !== 'function') {
+    logger.warn('engine.io shape is unexpected; skipping WS packing patch');
+    return;
+  }
+

Evidence

The function sets installed = true and then can return early from the catch or from the shape
guard, leaving the patch uninstalled but preventing any future calls from doing work due to the `if
(installed) return;` guard.

src/node/utils/EnginePacking.ts[38-58]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`installEngineWsPacking()` marks the patch as installed before confirming that it can actually install. If module resolution fails or the engine.io shape check fails, the function returns with `installed === true`, blocking any later attempt to install in the same process.

## Issue Context
This module is explicitly intended to be idempotent and safe to call from multiple boot paths. The current flow makes failures “sticky” within the process lifetime.

## Fix Focus Areas
- src/node/utils/EnginePacking.ts[38-58]

## Proposed fix
- Move `installed = true` to *after* all require/shape validation passes and immediately before/after the prototype is successfully wrapped.
- Optionally, use a second flag (e.g. `installing`) to avoid double-wrapping if re-entrancy is a concern, but do not permanently set `installed` on failure.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The patch captures WebSocketTransport.prototype.send without verifying it is a function, then
unconditionally calls originalSend.call(...) in the single-packet path, which will throw a
TypeError if send is missing or non-callable for the resolved transport export.

Code

src/node/utils/EnginePacking.ts[R60-70]

+
+  WebSocketTransport.prototype.send = function (packets: any[]) {
+    // Single-packet sends keep the legacy fast path: per-frame encoding
+    // including the pre-encoded-frame optimisation. Only fan-out bursts
+    // (writeBuffer accumulated more than one packet between flushes) are
+    // packed — for the steady state of a quiet pad, behaviour is identical
+    // to the upstream implementation.
+    if (!Array.isArray(packets) || packets.length < 2) {
+      return originalSend.call(this, packets);
+    }
+

Evidence

The code stores originalSend without a type check and then uses originalSend.call(...) when
packets.length < 2, which will throw if originalSend is not a function.

src/node/utils/EnginePacking.ts[60-70]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The patch assumes `WebSocketTransport.prototype.send` exists and is callable. If the resolved `WebSocketTransport` export is not the expected engine.io transport (or if engine.io changes), `originalSend` may be `undefined` or non-function, and the single-packet fast path will crash when calling `originalSend.call(...)`.

## Issue Context
There is already a shape check for `WebSocketTransport` and `encodePayload`, but it does not check the presence/type of `WebSocketTransport.prototype.send`.

## Fix Focus Areas
- src/node/utils/EnginePacking.ts[60-70]

## Proposed fix
- Add `if (typeof originalSend !== 'function') { logger.warn(...); return; }` before overriding the prototype.
- If you keep the early `installed` flag, ensure it is not left `true` when you return due to this validation (ideally combined with the fix from the other finding).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools